home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Aminet 8
/
Aminet 8 (1995)(GTI - Schatztruhe)[!][Oct 1995].iso
/
Aminet
/
dev
/
c
/
c2local.lha
/
c2local
/
c2local.dok
< prev
next >
Wrap
Text File
|
1995-06-30
|
19KB
|
483 lines
C2Local V1.0
============
© 1994-95 by Matthias Meixner
Copyright
---------
C2Local, CComp, CTMerge, StrMerge (C) Copyright 1994-95 by Matthias Meixner.
Alle Rechte vorbehalten.
Für die rechtlichen Aspekte, lesen Sie bitte auch die Liesmich Datei.
Hintergrund
-----------
Seit der Version 2.1 des Amiga-Betriebssystems ist es möglich Programme
mehrsprachig auszulegen. Dies wird über sogenannte Kataloge realisiert.
Dabei wird eine Sprache in das Programm eincompiliert und die anderen
Übersetzungen in Katalogen abgelegt. Zur Laufzeit des Programms wird nun
die passende Sprache bestimmt und über den zugehörigen Katalog in das
Programm eingebunden. Nun erfordert dies aber, daß in den Sourcecodes die
Strings nicht mehr direkt als Strings dargestellt werden können, da sie
ja von der eingestellten Sprache abhängen. Ziel von C2Local war es zu
ermöglichen, daß der Sourcecode weiterhin auf die vertraute Art geschrieben
werden kann und man danach vollautomatisch eine lokalisierte Version
generieren kann. Dieses Ziel wird mit C2Local für C und C++ Sourcecodes
fast vollständig erreicht. Programme wie CatComp generieren zwar Code zum
ansprechen von lokalisierten Strings, doch der Programmierer muß den
Sourcecode selbst daraufhin anpassen. "Localize" geht zwar einen Schritt
weiter und kann den Sourcecode selbständig patchen, ist aber auf Strings
innerhalb von Funktionen beschränkt, so daß z.B. Strukturen von Menüs
manuell lokalisiert werden müssen. C2Local kann dagegen die meisten dieser
Strings lokalisieren. Die einzige Ausnahme ist, daß char-Arrays nicht
statisch mit diesen Strings initialisiert werden können.
z.B. ist
char a[]="test"
nicht automatisch lokalisierbar. Aber der viel häufiger benötigte Fall
char *a="test"
kann automatisch lokalisiert werden. Dieser Fall tritt unter anderem bei
der Initialisierung von Systemstrukturen auf, so daß z.B. Menüs oder Gadgets
ohne Probleme automatisch lokaliert werden können.
Systemanforderungen
-------------------
Die Programme benötigen mindestens OS2.0 (V37). Die mit c2local lokalisierten
Programme benötigen keine andere Betriebssystemversion als das Original,
allerdings wird die Lokalisierung nur ab OS2.1 wirksam.
Programme
---------
Dieses Programmpaket enthält folgende Programme:
C2Local: Programm zum Generieren von lokalisierten Sourcecodes
CComp: Programm zum Übersetzen von Katalogen
CTMerge: Programm zum Mischen von Übersetzungsdateien
StrMerge: Programm zum Mischen von Stringdateien
Diese Programme befinden sich im Bin-Directory.
Installation
------------
Es reicht zur Installation aus das C2Local Verzeichnis an die gewünschte
Stelle zu kopieren und das Bin-Verzeichnis in den Suchpfad aufzunehmen.
Falls man die Programme in ein anderes Verzeichnis kopieren möchte, muß man
nur darauf achten, daß man das zugehörige Catalogs-Verzeichnis mitkopiert.
Es muß sich im gleichen Verzeichnis wie die Programme befinden, damit die
deutschen Strings der Lokalisierung gefunden werden können. Ansonsten ist
nur die eingebaute englische Version verfügbar. Dies gilt auch für den Fall,
daß Sie mit einer Version des Betriebssystems arbeiten, die die Lokalisierung
noch nicht unterstützt.
Bedienung
---------
C2Local Scan/S,Patch/S,Compile/S,Pattern/M,Ign=Ignore/K,Lab=Labels/K,
Cat=Catalog/K,Lang=Language/K,Ver=Version/N,Name/A/K
NAME dient als Basisname, aus dem alle Namen der zu erzeugenden Dateien
abgeleitet werden.
C2Local kennt drei verschiedene Betriebsarten: Scan, Patch und Compile.
'Scan' durchsucht alle Dateien, die dem Pattern entsprechen, nach Strings und
erzeugt eine Stringdatei <Name>_locale.str, die alle Strings enthält. Die
Zeilen dieser Datei sind folgendermaßen aufgebaut:
<Label> <String> [<Größe>]
^^^^^^^ Dieses Feld wird hier nicht erzeugt, kann jedoch
für die Verwendung mit 'Compile' mit einem Editor
angehängt werden.
Ein '+' am Ende eines Strings zeigt an, daß sich der String auch noch über
die nächste Zeile erstreckt. Mit IGNORE kann man bestimmte Strings aus
dieser Liste ausschließen, mit LABEL den Labels bestimmte Werte zuweisen.
Diese Dateien sind genauso aufgebaut, wie die von Scan erzeugte Datei, wobei
in der Datei für IGNORE das Feld <Label> weggelassen werden kann.
Typischerweise wird man also zuerst einmal mit 'Scan' alle Dateien
durchsuchen lassen und dann in der erzeugten Datei alle Strings, die nicht
lokalisiert werden sollen, herraussuchen und abspeichern. Ist dies nicht
genau genug, so kann man Strings auch dadurch ausschließen, daß man im
Sourcecode direkt hinter den String ohne Leerzeichen '/*-' schreibt, also
z.B.
char *a="wird nicht lokalisiert"/*-*/;
Kommentare beginnen wie in C++ mit // und markieren den Rest der Zeile als
Kommentar.
'Patch' macht zunächst einmal genau das gleiche wie 'Scan', erzeugt jedoch
ein neues Directory 'Localized', kopiert alle Dateien, die im Pattern
angegeben waren in dieses Directory und ersetzt die Strings durch die Label
aus der neu erzeugten Stringdatei. ACHTUNG: will man die automatisch
generierten Labels durch eigene ersetzen, so kann man dies nicht dadurch tun,
daß man die Stringdatei <Name>_locale.str einfach editiert und danach
C2Local mit 'Patch' startet, da 'Patch' diese Datei neu erzeugt und dadurch
überschreibt. Stattdessen muß man die editierte Datei umbenennen und mit
'Label' als Parameter beim Aufruf von C2Local angeben.
Hat man bereits eine Datei mit den Strings, die nicht lokalisiert werden
sollen, und möchte den Labels keine eigenen Namen geben, bzw. hat bereits
eine Datei mit diesen Namen, so kann man auf 'Scan' ersatzlos verzichten.
'Compile' erzeugt aus <Name>_locale.str, die Dateien:
Localized/<Name>_locale.cd Katalogbeschreibung
Localized/<Name>_locale.ct leere Katalogübersetzung
Localized/<Name>_locale.h Headerdatei, diese Datei wird per #include in
jede gepatchte Sourcecodedatei eingebunden
Localized/<Name>_locale.c C-Sourcecode mit allen verwendeten Strings
und der Routine InitStrings();
'Compile' benötigt folgende Optionen:
Catalog: Gibt den Katalognamen an, der später verwendet werden soll.
Version: Versionsnummer des Katalogs (ACHTUNG im Unterschied zu
OpenLibrary muß bei OpenCatalog, das in InitStrings() verwendet
wird die Versionsnummer exakt übereinstimmen, wenn sie ungleich
0 ist !!) (default: 0)
Language: Dies gibt die eigebaute Sprache an. (default: english)
Diese Werte werden in InitStrings() einkodiert !
Die Routine InitStrings() muß vom eigenen Programm aus aufgerufen werden.
Am besten ist es, wenn man sie als erste Routine in main() aufruft. Damit
man dies bereits im Original-Sourcecode machen kann, dies gleichzeitig aber
nicht beim compilieren der Originalversion stört macht man dies am besten
so:
#ifdef __LOCALIZED
InitStrings();
#endif
__LOCALIZED wird in Localized/<Name>_locale.h definiert. Da diese Datei per
#include in die gepatchten Sourcen eingebunden wird, wird InitStrings()
in der lokalisierten Version dann automatisch verwendet.
Lokalisieren
------------
Voraussetzung für eine erfolgreiche Lokalisierung mit C2Lokal ist, daß
Strings grundsätzlich nur gelesen werden, da mehrfache Vorkommen von Strings
auf den gleichen String abgebildet werden. Wird dieser String geändert, so
ändern sich alle Strings mit gleichem Inhalt im ganzen Programm. Genau dies
wird nämlich ausgenutzt um die Strings durch ihre lokalisierten Versionen
zu ersetzen.
Typischerweise wird man bei der Lokalisierung eines Programms
folgendermaßen vorgehen:
Zuerst wird man sich einmal alle Strings heraussuchen lassen, z.B.:
C2Local SCAN #?.c #?.h NAME test
Aus test_locale.str löscht man alle Strings, die lokalisiert werden sollen
und speichert sie als ignore.str. Da normalerweise später niemand die
lokalisierten Sourcecodes lesen wird, braucht man auf die Namen der Labels
keine Rücksicht zu nehmen.
Nun kann man den lokalisierten Sourcecode erzeugen:
C2Local PATCH #?.c #?.h NAME test IGNORE ignore.str
Sollte dabei die Meldung auftreten, daß die Catalog-Translation-Datei nicht
neu angelegt wurde, da sie bereits existiert, so muß man diese Datei
umbenennen oder löschen und nocheinmal 'Patch' aufrufen. Dies hat den Sinn,
daß nicht mühsam erstellte Übersetzungen aus Versehen überschrieben werden.
C2Local COMPILE NAME test VERSION 1 CATALOG test.catalog
erzeugt die restlichen noch fehlenden Dateien und danach kann alles bereits
compiliert werden:
cd Localized
sc #?.c link // z.B. Für SAS-C
Sollten dabei Fehler auftreten, während vorher keine Fehler aufgetreten sind,
dann handelt es sich vermutlich um eine der oben erwähnten Ausnahmen.
Jetzt kommt der aufwendigste Teil, das Übersetzen der Strings :)
Zuerst sollte man sich die leere Catalog-Translation-Datei <Name>_locale.ct
kopieren, damit sie noch für weitere Übersetzungen zur Verfügung steht. In
diese Datei trägt man die übersetzen Strings ein. Dabei enthalten die
Kommentarzeilen, die mit ';' beginnen den Originalstring. Ein Eintrag sieht
ungefähr folgendermaßen aus:
Label
deutscher String
; english String
;
WICHTIG: Die Kommentarzeilen dürfen nicht verändert werden, wenn man CTMerge
verwenden will !!!!!
Innerhalb der Übersetzung können C-Escape-Sequenzen verwendet werden
inclusive ein paar Erweiterungen (siehe Tabelle)
Ein Backslash ('\') am Ende der Zeile zeigt an, daß dieser String in der
nächsten Zeile fortgesetzt wird.
Tip: Da manche Texteditoren Leerzeichen am Zeilenende abschneiden, kann man
\ hinter die Leerzeichen setzen und in der folgenden Zeile eine
Leerzeile einfügen.
Kommentarzeilen beginnen mit ';' in der ersten Spalte.
Beim Ausfüllen sollte man nicht vergessen hinter '## language' die Sprache
des Katalogs einzutragen und hinter '## version' die Version des Katalogs.
Diese wird als Standart-Versionsstring angegeben.
Aus dieser Übersetzung kann man nun mit CComp einen Katalog bauen:
CComp <name>_locale.cd übersetzung.ct Catalogs/deutsch/test.catalog
Sollte dabei die Fehlermeldung auftreten, daß ein übersetzter String zu lang
ist, so kann man die für einen String reservierte Länge ändern, indem man
in der Stringdatei hinter dem String die maximal vorkommende Länge aller
Übersetzungen angibt, z.B.:
msg_0 "Teststring" 20
Als default wird die doppelte Länge des Strings angenommen, wenn kein Wert
angegeben wird. Diesen Wert kann man auch dazu benutzen, um den Speicherbe-
darf von langen Strings einzuschränken, allerdings sollte man dabei bedenken,
daß Strings in anderen Sprachen deutlich länger sein können. Wenn man auf
diese Art eine Stringdatei (hier test_locale.str) geändert hat, so ist es
notwendig C2Local noch einmal mit 'Compile' aufzurufen und das Programm neu
zu compilieren, damit die neu erzeugten Sourcecodes wieder eingebunden
werden.
Wichtig: Der Name der Katalogs muß mit dem Namen übereinstimmen, der bei
'Compile' verwendet wurde !
Anstelle von CComp kann man natürlich auch CatComp, FlexCat, KitCat, MakeCat
oder eines der anderen Katalogtools verwenden.
Das wars!
Falls andere Sprachen trotz einer entsprechenden Einstellung in den
Preferences nicht verwendet werden:
- befindet sich der Katalog im richtigen Verzeichnis ?
- stimmt der Name des Katalogs ?
- stimmt die Version des Katalogs ?
- ist im .ct-file die Sprache eingetragen, Tippfehler ?
- ist noch ein alter Katalog im Speicher (evtl. "avail flush") ?
- wurde InitStrings() aufgerufen ?
Funktionsweise
--------------
C2Local sucht alle Strings und ersetzt sie durch ein Label. Dieses Label ist
eine Referenz auf den String, der in eine Struktur eingebettet wurde, um es
zu ermöglichen die Strings zu verketten. Die Strings sind dabei als Array
angegeben. Dies bedingt allerdings die Einschränkung, daß sie eine bestimmte
Länge nicht überschreiten dürfen, bietet allerdings den Vorteil, daß man sie
überschreiben kann,ohne daß sich dabei ihre Adresse ändert. Ihre Adresse
ist also bereits beim Compilieren/Linken bekannt und kann in statischen
Initialisierungen verwendet werden. Beim Aufruf von InitStrings wird
nun versucht der Katalog zu öffnen. Falls dies möglich ist, wird jeder
String durch seine Übersetzung Überschrieben.
Da Strings nun in Arrays stehen, kann man allerdings keine weiteren Arrays
damit initialisieren, wodurch es zu den oben genannten Ausnahmen bei der
automatischen Lokalisierung kommt. Man kann den Sourcecode jedoch etwas
anpassen, um dies trotzdem zu ermöglichen. Falls dieses Array nur gelesen
wird, so kann man es Grundsätzlich durch einen Zeiger auf den String ersetzt
werden:
char a[]="test"; -> char *a="test";
Lokale Arrays kann man recht einfach ersetzen:
test() { -> test() {
char a[10]="String"; -> char a[10];
} -> strcpy(a,"String");
-> }
Globale Arrays muß man leider per Hand inititalisieren:
char a[10]="String"; -> char a[10];
->
main() { -> main() {
} -> strcpy(a,"String");
-> }
Für statische lokale Arrays gibt es zwei Möglichkeiten:
1) Man macht daraus eine globale Variable und inititalisiert sie beim
Programmstart
2)
test() { -> test() {
static char a[10]="String"; -> char a[10];
} -> static int init=0;
-> if(!init) {
-> strcpy(a,"String");
-> init=1;
-> }
-> }
Die anderen Programme im Paket
------------------------------
CComp Catalogdescription/A,Translation/A,Catalog/A
CComp dient zum Erzeugen von Katalogdateien. Es benötigt drei Parameter.
Eine Katalogbeschreibungsdatei (Endung .cd), eine Katalogübersetzungsdatei
(Endung .ct) und den Namen des zu erzeugenden Katalogs.
CTMerge From/A,Merge/A/M,To/K/A
CTMerge mischt zu der Katalogübersetzung 'From' alle Katalogübersetzungen
'Merge' und schreibt das Ergebnis nach 'To'. 'From' und 'To' müssen
verschiedene Dateien sein !! CTMerge verwendet dabei die Kommentarzeilen,
um bereits bekannte Übersetzungen aus den 'Merge'-Dateien zu erkennen und in
die Ausgabedatei einzukopieren. Die Labelnamen werden dabei nicht verändert.
Auf diese Weise kann man recht schnell neue Übersetzungen erstellen, wenn
ein Programm erweitert wurde und neue Strings hinzugekommen sind. Man kann
nicht einfach die alte Übersetzungsdatei direkt verwenden solange man
automatisch generierte Labelnamen verwendet hat, da sich die Labelnamen
vermutlich seit der letzen Version verändert haben. In diesem Fall kann man
deshalb CTMerge verwenden, um sich eine komplette Neuübersetzung zu sparen.
StrMerge From/A,Merge/A/M,To/K/A
StrMerge mischt Längenangaben in Stringfiles. Manchmal ist es notwendig,
Strings explizit eine Maximallänge zuzuweisen. Dies kann man durch editieren
der Stringdatei <name>_locale.str vor dem 'Compile' Aufruf von C2Local
machen; da diese Datei bei jedem 'Scan' oder 'Patch' überschrieben wird,
wäre es wünschenswert dies automatisch vornehmen zu lassen. StrMerge macht
genau dies. Es extrahiert die Längenangaben aus den 'Merge'-Dateien und
kombiniert sie mit der vorgegebenen Stringdatei. 'From' und 'To' darf die
gleiche Datei sein. Damit wird es möglich Batch-Dateien für die
Lokalisierung eines Programms zu schreiben.
Zusätzliche Informationen zu den Dateiformaten
----------------------------------------------
Endung: Beschreibung:
.cd eine 'Catalog Description'-Datei
Sie enthält die Nummern, Kennungen und Originaltexte, sowie die
Längenbegrenzungen für die Übersetzungen.
Bsp: Text1_STR (22/7/80)
Hallo Leute, ein deutscher String !
Das Beispiel weist dem String Nr. 22 die Kennung Text1_STR und den
Text in der zweiten Zeile zu. Die minimale Länge der Übersetzungen
muß 7, die maximale Länge 80 betragen. Diese Angaben sind optional,
(//) ist also genauso gültig.
Kommentarzeilen beginnen mit ';'.
'\' in einer Stringzeile bedeutet, daß die Zeile in der nächsten
Zeile weitergeht.
Escape-Codes: siehe Tabelle.
Nähere Informationen siehe Doc-File zu CatComp !
.ct: eine 'Catalog Translation'-Datei
Sie enthält die Übersetzungen in einer bestimmten Sprache.
Bsp: Text1_STR
C'est français !
; Hallo Leute, ein deutscher String !
Der sog. Header enthät außerdem weitere Informationen:
## version $VER: name.catalog ver.rev (10.09.92)
## language français
Kommentarzeilen beginnen mit ';'.
Kommentare sollten nicht gelöscht oder verändert werden,
da sie von CTMerge benötigt werden (also für CTMerge eigentlich
gar keine sind)!
'\' in einer Stringzeile bedeutet, daß die Zeile in der nächsten
Zeile weitergeht.
Escape-Codes siehe Tabelle.
Nähere Informationen siehe Doc-File zu CatComp !
.str Stringdatei
Sie enthält die Strings:
<Label> <String> [<Größe>]
Bsp: msg_0 "String" 10
Strings können über mehrere Zeilen gehen:
Bsp: msg_0 "Str"+
"ing"
<Label> ist für Ignore-Dateien und Dateien, die mit StrMerge
dazugemischt werden, optional. <Größe> ist immer optional
(default: 2*Länge des Strings).
Tabelle der Escape-Codes
--------------------------
\a Beep (ASCII 7)
\b Backspace (ASCII 8)
\c Control Sequence Introducer CSI (ASCII 155)
\e ESC (ASCII 27)
\f Formfeed (ASCII 12)
\n Newline (ASCII 10)
\r Carriage Return (ASCII 13)
\t Tab (ASCII 9)
\v Vertical Tab (ASCII 11)
\xNN ASCII-Code NN (Hexadezimal)
\NNN ASCII-Code NNN (Oktal)
\\ Backslash (\)
Ein Backslash ('\') am Ende der Zeile zeigt an, daß dieser String in der
nächsten Zeile fortgesetzt wird.
Der Autor
---------
Fragen, Bug-Reports oder sonstiges schicken Sie bitte an:
Matthias Meixner
Sandberg 13
36145 Schwarzbach
Deutschland
oder EMail:
meixner@rbg.informatik.th-darmstadt.de